<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>User Guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css" />
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="alias.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="alias.js"></script>

<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>



<script type="text/javascript">
  jQuery(document).ready(function () {
    if(gref){ // Number all _img and _table classes
      gref();
    }
  });
</script>

</head>
<body>
<div id="top"><!-- do not remove this div! -->

<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">nRF Gazell
   &#160;<span id="projectnumber">version 0.4.2</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('group__gzll__02__user__guide.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">User Guide</div>  </div>
<div class="ingroups"><a class="el" href="group__modules__01__gzll.html">Gazell Link Layer</a></div></div>
<div class="contents">
<h2><a class="anchor" id="gzll_intro"></a>
Introduction</h2>
<p>The Gazell Link Layer is a protocol for setting up a robust wireless link between typically one single Host and up to eight Devices in a star network topology. The Gazell Link Layer is a protocol designed to minimize power consumption in power-sensitive wireless desktop products and is also suitable for a range of other wireless applications.</p>
<p>In the rest of this text we will replace "Gazell Link Layer" simply with "Gazell".</p>
<p>Gazell takes advantage of the fact that one end of the communication can be "always on" in order to minimize the power consumption of the power-sensitive devices on the other end. The prototypical example of this is a wireless mouse communicating with a USB dongle. Moreover, Gazell has a sophisticated but easy-to-use channel switching and synchronization scheme, that gives robustness to interference and good wireless coexistence properties while still enabling high-throughput and low latency.</p>
<h2><a class="anchor" id="features"></a>
Features</h2>
<ul>
<li>Supports a star network topology with one Host and up to 8 Devices (pipes).</li>
<li>Bi-directional data transfer between each Host and Device.</li>
<li>Channel hopping functionality that gives a high rate and reliable wireless link in environments with interference from other radio sources.</li>
<li>Packet acknowledgement and automatic packet retransmission functionality to prevent data loss.</li>
<li>Individual TX and RX FIFOs for every data pipe.</li>
<li>Backward compatible with legacy nRF24Lxx Gazell.</li>
<li>Devices self-synchronize to the Host, meaning:<ul>
<li>No connection packets are required to setup a link.</li>
<li>No polling packets are required to maintain a link.</li>
<li>Devices can enter and remove themselves from the network at any time.</li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="modes"></a>
Gazell modes</h2>
<p>Gazell supports a star network, where each node has a mode determining its role; one node is in <b>Host</b> mode and is "always on" while the remaining nodes are in <b>Device</b> mode. Each Gazell Host can communicate with up to 8 Gazell Devices. Each Device communicates to a single Host.</p>
<div class="image">
<img src="gzll_fig1_star_network.png" alt="gzll_fig1_star_network.png"/>
<div class="caption">
Gazell star network</div></div>
<p> Once enabled, the Host in a Gazell network is always listening, and it is the Device that always initiates a communication. Each packet that a Device sends is required to be acknowledged by the Host. It is possible for the Host to send data to the Device by piggybacking data to an acknowledgement (ACK) packet. Therefore a Host has to wait for a packet from a Device before it can send any data to it.</p>
<p>It is possible to build more sophisticated Gazell networks, since a single Device is able to speak to several Hosts and any node is able to change between the two modes. However, this requires the application to coordinate such a network. Therefore, we focus here on the typical use-case as a star network with static modes.</p>
<h2><a class="anchor" id="getting_started"></a>
Getting started with Gazell</h2>
<p>Gazell handles automatically all synchronization and packet handling. All the user is required to do is to add payloads to the transmit (TX) FIFOs and read payloads from the receive (RX) FIFOs. Gazell automatically notifies the application when a packet is received.</p>
<p>The typical Gazell application has the following steps:</p>
<ul>
<li>Initialize Gazell using <a class="el" href="group__gzll__02__api.html#gacba07d9c893b4673c563ced97cccba94" title="Initialize Gazell.">nrf_gzll_init()</a>.</li>
<li>Reconfigure Gazell's default parameters. At a minimum the addresses and channels should be reconfigured to avoid interfering with other Gazell networks.</li>
<li>Enable Gazell using <a class="el" href="group__gzll__02__api.html#gadfb1003b245b019481334e6d087f928e" title="Enable Gazell.">nrf_gzll_enable()</a>.</li>
<li>If the node is a Device, start sending:<ul>
<li>Add payloads to the TX FIFO using <a class="el" href="group__gzll__02__api.html#ga1c0b1d1838e032af28c35d7c3e0603e0" title="Add a packet to the tail of the TX FIFO.">nrf_gzll_add_packet_to_tx_fifo()</a>.</li>
<li>Handle the returned ACK packet when the <a class="el" href="group__gzll__02__api.html#gac1306762dc2ccfc5c2bbdbe2d85a93aa" title="ACK received callback (Device mode only).">nrf_gzll_device_tx_success()</a> callback is called. Fetch the payloads from the RX FIFO using <a class="el" href="group__gzll__02__api.html#ga419c8ce6a3e08d5dec8b50ef88b3cc2b" title="Fetch a packet from the head of the RX FIFO.">nrf_gzll_fetch_packet_from_rx_fifo()</a>.</li>
<li>Handle the failed packet transmissions when the <a class="el" href="group__gzll__02__api.html#ga0642fed399ed3ec41406cd4323edf5ad" title="Transmission failed callback (Device mode only).">nrf_gzll_device_tx_failed()</a> callback is called. Failed packets are automatically removed from the TX FIFO.</li>
</ul>
</li>
<li>If the node is a Host, start listening:<ul>
<li>Handle the received data packets when the nrf_gzll_host_packet_received() calbback is called. Fetch the packets from the RX FIFO using nrf_gzll_fetch_from_rx_firo().</li>
<li>Add any payloads to send to the TX FIFO using <a class="el" href="group__gzll__02__api.html#ga1c0b1d1838e032af28c35d7c3e0603e0" title="Add a packet to the tail of the TX FIFO.">nrf_gzll_add_packet_to_tx_fifo()</a>.</li>
</ul>
</li>
</ul>
<p>Gazell can also be disabled at any time using the <a class="el" href="group__gzll__02__api.html#ga20e0e3ca35dda6b9220b1ddce7565687" title="Disable Gazell.">nrf_gzll_disable()</a> function. When this is called Gazell will complete any ongoing transmission or reception before being disabled (That is, until the end of the current timeslot, a concept we explain later in the section on <a class="el" href="group__gzll__02__user__guide.html#timeslot">Timeslots</a>). When the disabling operation is complete, Gazell will call the <a class="el" href="group__gzll__02__api.html#ga722e2ee917072fca60a50a23d8c84414" title="Disabled callback.">nrf_gzll_disabled()</a> function. By the time this callback is made, the Gazell CPU context, radio and Gazell timer will have stopped. It is now possible to call any of the configuration set functions, which will be in force, once Gazell is enabled again.</p>
<h2><a class="anchor" id="package_transaction"></a>
Package transactions</h2>
<p>A typical packet transaction between a Device and a Host consists of a Device initiating the transaction by sending a data packet to the Host after which the Host sends an ACK packet in return.</p>
<p>When an ACK packet is received by the Device, it knows that the initial packet was successfully transmitted and the <a class="el" href="group__gzll__02__api.html#gac1306762dc2ccfc5c2bbdbe2d85a93aa" title="ACK received callback (Device mode only).">nrf_gzll_device_tx_success()</a> callback function will be called to notify the application of this.</p>
<p>Similarly, when the initial packet is received by the Host, the <a class="el" href="group__gzll__02__api.html#ga116b8ce684c3f6fe8c63c371b913aa3e" title="Data packet received callback (Host mode only).">nrf_gzll_host_rx_data_ready()</a> callback function will be called to notify to the application that a new packet has been received.</p>
<p>Note that these callback functions are actually queued so that the application avoids race conditions. This is discussed later in the section <a class="el" href="group__gzll__02__user__guide.html#callback_queueing">Callback queueing</a>.</p>
<div class="image">
<img src="gzll_fig7_host_dev_trans_ok.png" alt="gzll_fig7_host_dev_trans_ok.png"/>
<div class="caption">
Successful packet transaction</div></div>
<p> A transaction can fail, because either:</p>
<ul>
<li>the initial packet from the Device was not received correctly by the Host,</li>
<li>or the corresponding ACK packet was not received correctly by the Device. Note that packets with a failing Cyclic Redundancy Check (CRC) are ignored by Gazell.</li>
</ul>
<p>If a transaction fails the Device will attempt to retransmit the initial packet to the Host until the ACK is finally received or the maximum number of transmission attempts is reached. If the maximum number of transmission attempts is reached the retransmissions will stop and the <a class="el" href="group__gzll__02__api.html#ga0642fed399ed3ec41406cd4323edf5ad" title="Transmission failed callback (Device mode only).">nrf_gzll_device_tx_failed()</a> callback will be called.</p>
<p>In the case where only the ACK packet sent from the Host to the Device is lost, but both the initial packet and the subsequent retransmission attempts are being successfully received by the Host, the repeated packets will be discarded by the Host, but the ACK packets will still be sent in return to the Device. This prevents the application receiving duplicate data packets at the Host.</p>
<div class="image">
<img src="gzll_fig8_host_dev_trans_fail.png" alt="gzll_fig8_host_dev_trans_fail.png"/>
<div class="caption">
Example on failing package transaction. Here, the maximum number of allowed transmission attempts is set to 3.</div></div>
 <h2><a class="anchor" id="packet_id"></a>
Packet identification</h2>
<p>Any packet transmitted from a Device to a Host is uniquely identified by a two bit packet ID field in the packet header together with the packet's 16-bit Cyclic Redundancy Check (CRC). This packet ID is used to distinguish a new packet from the previous packet if it has the same payload.</p>
<p>At the Host, retransmitted packets will be discarded and not added to an RX FIFO.</p>
<h2><a class="anchor" id="FIFOs"></a>
FIFO handling</h2>
<p>All eight pipes on both the Device and the Host have two First-in First-out (FIFO) buffers that can hold packets. We call these FIFO buffers simply FIFOs. Each pipe has a TX FIFO and an RX FIFO.</p>
<h3><a class="anchor" id="dev_fifo"></a>
Device FIFO handling</h3>
<p>When Gazell is enabled in Device mode, any packets uploaded to a TX FIFO will be transmitted at the next opportunity. If several TX FIFOs contain packets, the various TX FIFOs will be serviced in a round robin fashion, meaning that no TX FIFOs will experience starvation even when packets are continuously being added to other TX FIFOs.</p>
<p>When an ACK is successfully received from a Host, it implies that the payload was successfully received and added to the Host's RX FIFO, the successfully transmitted packet will be removed from the TX FIFO so that the next packet in the FIFO can be transmitted.</p>
<p>If an ACK received by a Device contains a payload, this payload will be added to the pipe's RX FIFO.</p>
<p>If the RX FIFO for a specific pipe on a Device is full and can not accommodate any new packets, no new packets will be sent from the Device on this pipe. In this case, we will never end up in the situation where a payload received in an ACK will have to be discarded due to the pipe's RX FIFO being full.</p>
<p>In addition, Gazell limits the total number of packets in the FIFOs, which is smaller than the total size of all the FIFOs. Therefore, a Device will also refuse to add a packet to the TX FIFO if it doesn't have space for the packet as well as the corresponding ACK.</p>
<h3><a class="anchor" id="host_fifo"></a>
Host FIFO handling</h3>
<p>When Gazell is enabled in Host mode, all enabled pipes (addresses) are simultaneously monitored for incoming packets.</p>
<p>If a new packet not previously added to the pipe's RX FIFO is received, and the pipe's RX FIFO has available space for the packet, the packet will be added to the RX FIFO and an ACK will be sent in return to the Device. If the pipe's TX FIFO contains any packets, the next serviceable packet in the TX FIFO will be attached as a payload in the ACK packet. In order for a TX packet to be attached to an ACK, this TX packet would have to be uploaded to the TX FIFO before the packet is received.</p>
<p>As we can not ensure that the ACK always will be successfully received by the Device, the data payload added to the ACK will not be removed from the TX FIFO immediately. This TX packet will be removed from the TX FIFO when a new packet (new packet ID or CRC) is received on the same pipe. In this case, the new packet sent as an ACK will serve as a kind of acknowledgement from the Device saying that the previous ACK from the Host was successfully received by the Device. ACKs sent in reply to retransmission attempts will all contain the same TX payload.</p>
<p>When the Host is handling packets on multiple pipes, care needs to be taken to ensure that ACK payloads in the TX FIFOs on pipes that are no longer in use, are not taking up space in the memory pool and consquently blocking communication on other pipes. To avoid such congestion, the application on the Host can flush the TX FIFOs on the pipes no longer in use.</p>
<h2><a class="anchor" id="callback_queueing"></a>
Callback queueing</h2>
<p>Gazell contains an internal callback queue for queueing pending callbacks in the case where Gazell attempts to call a new callback function while the application is already servicing a previously called callback function.</p>
<p>As an example, if a new packet is being received by a Host while the application is already servicing the <a class="el" href="group__gzll__02__api.html#ga116b8ce684c3f6fe8c63c371b913aa3e" title="Data packet received callback (Host mode only).">nrf_gzll_host_rx_data_ready()</a> callback from a previously received packet, the <a class="el" href="group__gzll__02__api.html#ga116b8ce684c3f6fe8c63c371b913aa3e" title="Data packet received callback (Host mode only).">nrf_gzll_host_rx_data_ready()</a> callback for the latest packet will be added to the callback queue and serviced at a later opportunity. In this case, <a class="el" href="group__gzll__02__api.html#ga116b8ce684c3f6fe8c63c371b913aa3e" title="Data packet received callback (Host mode only).">nrf_gzll_host_rx_data_ready()</a> will be called one time for every received packet, and the application does not need to handle the potential race condition scenario where a new packet is being received just before the application is about to exit the <a class="el" href="group__gzll__02__api.html#ga116b8ce684c3f6fe8c63c371b913aa3e" title="Data packet received callback (Host mode only).">nrf_gzll_host_rx_data_ready()</a> function.</p>
<p>Similarly, on a Device the <a class="el" href="group__gzll__02__api.html#gac1306762dc2ccfc5c2bbdbe2d85a93aa" title="ACK received callback (Device mode only).">nrf_gzll_device_tx_success()</a> callback will be called one time for every packet receiving an ACK, even when a new packet is receiving an ACK while the application is servicing the <a class="el" href="group__gzll__02__api.html#gac1306762dc2ccfc5c2bbdbe2d85a93aa" title="ACK received callback (Device mode only).">nrf_gzll_device_tx_success()</a> callback of a previously transmitted packet.</p>
<p>The size of the callback queue is given by NRF_GZLL_CONST_CALLBACK_QUEUE_LENGTH.</p>
<h2><a class="anchor" id="timeslot"></a>
Timeslots</h2>
<p>A core parameter in Gazell is the <b>timeslot</b>. The timeslot can be seen as the internal Gazell "heartbeat".</p>
<p>In a Device, any packet transmission (both new packets and retransmitted packets) will start at the start of a timeslot, and only one packet transaction (including ACK) can take place within a timeslot.</p>
<div class="image">
<img src="gzll_fig2_device_heartbeat.png" alt="gzll_fig2_device_heartbeat.png"/>
<div class="caption">
Relation between Device operation and timeslot</div></div>
<p> And similarly, in a Host, the RF channel only changes at the start of a timeslot.</p>
<div class="image">
<img src="gzll_fig3_host_heartbeat.png" alt="gzll_fig3_host_heartbeat.png"/>
<div class="caption">
Relation between Host operation and timeslot</div></div>
<p> The period for the heartbeat is set using the <a class="el" href="group__gzll__02__api.html#ga3347094a64c07793c773c4fdf4bc4bff" title="Set the timeslot period.">nrf_gzll_set_timeslot_period()</a> function.</p>
<h2><a class="anchor" id="freq"></a>
Frequency hopping</h2>
<p>To ensure good coexistence performance with other radio products operating in the same 2.4 GHz frequency band as Gazell, such as Wi-Fi or Bluetooth, Gazell implements mechanisms for hopping between various radio frequency channels.</p>
<p>When enabled, Gazell will pick channels from a predefined channel table.</p>
<p>The contents and size of this channel table can be reconfigured by the application, however the Device and Host should be configured to have the exact same channel table. In total the application can pick from a full channel set of 80 channels when specifying the channel table. Normally, a channel table of 3-7 channels has shown to give a satisfactory coexistence performance in most environments.</p>
<p>Having a too large channel table may increase the transmission latency and power consumption, while using a too small channel table may decrease the coexistence performance.</p>
<p>The core parameters deciding the channel hopping behavior are:</p>
<ul>
<li><b>timeslots_per_channel</b> (Applies for Host and "in sync" Device, set by <a class="el" href="group__gzll__02__api.html#gaf636a5a1aa2d4a791849de510b69a604" title="Set the number of timeslots that Gazell shall reside on a single channel before switching to another ...">nrf_gzll_set_timeslots_per_channel()</a>).</li>
<li><b>timeslots_per_channel_when_device_out_of_sync</b> (Applies for "out of sync" Device only, set by <a class="el" href="group__gzll__02__api.html#ga8a1bef2e6f32bd8dc55e9abde3007aed" title="Set the number of timeslots that a Gazell shall reside on a single channel before switching to anothe...">nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync()</a>).</li>
<li><b>channel_selection_policy</b> (Applies for "in sync" Device only, set by <a class="el" href="group__gzll__02__api.html#ga692ed4d88a064fdf9a4e69f939582911" title="Set the Device channel selection policy.">nrf_gzll_set_device_channel_selection_policy()</a>).</li>
</ul>
<p>Which one being used depends on whether Gazell is "in sync" or "out of sync" (these terms are closer described in the <a class="el" href="group__gzll__02__user__guide.html#synchronization">Synchronization</a> section). Therefore, we will not differentiate between these two terms and use the term <b>timeslots_per_channel</b> instead.</p>
<p>The <b>timeslots_per_channel</b> parameter decides the number of timeslots Gazell shall reside on a single channel before the channel shall be changed. When the next timeslot where a channel shift is performed, Gazell will pick the next channel from the predefined channel table, cycling back to the start of the channel table if required.</p>
<div class="image">
<img src="gzll_fig4_device_channel_switch.png" alt="gzll_fig4_device_channel_switch.png"/>
<div class="caption">
Device channel switching. Here, <b>timeslots_per_channel</b> = 2.</div></div>
 <div class="image">
<img src="gzll_fig5_host_channel_switch.png" alt="gzll_fig5_host_channel_switch.png"/>
<div class="caption">
Host channel switching. Here, <b>timeslots_per_channel</b> = 2.</div></div>
<p> In Device mode, <b>timeslots_per_channel</b> can also be seen as the number of transmission attempts to be spent on each channel before switching channel. This is because there is at most one transmission attempt for every timeslot.</p>
<p>The <b>channel_selection_policy</b> parameter is used by a Device being in sync to decide the initial channel to be used when sending a new packet to a Host (that is for the very first packet being sent, not for any following retransmission attempts).</p>
<p>Once synchronized with the Host, the Device can send either on the current channel that it believes the Host is on or on the last successful channel. This can be configured using the <a class="el" href="group__gzll__02__api.html#ga692ed4d88a064fdf9a4e69f939582911" title="Set the Device channel selection policy.">nrf_gzll_set_device_channel_selection_policy()</a>.</p>
<p>This <b>channel_selection_policy</b> parameter can take the following two values:</p>
<ul>
<li><a class="el" href="group__gzll__02__api.html#ggad45683bddfd8a170f89280b722f7744ca7ac745d687a1dc56962bed8a98ba719f">NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL</a></li>
<li><a class="el" href="group__gzll__02__api.html#ggad45683bddfd8a170f89280b722f7744ca97b439d85d2666cb9676c45f0db57a55">NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT</a></li>
</ul>
<p>By choosing the <a class="el" href="group__gzll__02__api.html#ggad45683bddfd8a170f89280b722f7744ca7ac745d687a1dc56962bed8a98ba719f">NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL</a> policy, the Device will start sending packets on the channel it last had a successfully acknowledged transmission. This policy is the most robust against static interferers as once the Device finds a quiet channel it should be able to successfully communicate with the Host.</p>
<p>By choosing the <a class="el" href="group__gzll__02__api.html#ggad45683bddfd8a170f89280b722f7744ca97b439d85d2666cb9676c45f0db57a55">NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT</a> policy, the Device sends on the channel it believes the Host is currently listening to. This achieves the lowest latency and highest throughput of the two policies as the Device does not have to wait for the Host to be listening on a specific channel. This policy is frequency hopping. The disadvantage of this policy is that if there is a static interferer on a particular channel, the Device will waste packets attempting to send on this channel. Note that the application can reconfigure the channel table during runtime to overcome this.</p>
<p>As mentioned, the channel selection policy only applies for the initial transmitted packet. If transmission of this initial packet fails, the following retransmission attempts will always be sent at the channel the Device beleievs the Host is monitoring.</p>
<p>If Gazell is "out of sync", Gazell will always start the packet transmission immediately using the previous successful transmission channel. If Gazell has never before transmitted a successful packet and thus has no "previous successful channel" to relate to, Gazell will start using the first channel in the channel table.</p>
<h2><a class="anchor" id="synchronization"></a>
Synchronization</h2>
<p>The internal timeslot, or "heartbeat", mechanism of Gazell is used to obtain synchronous communication while still enabling efficient channel switching. This mechanism is useful when a Device needs to switch to a new channel in the case when radio interference is being experienced on the current channel.</p>
<p>Each Gazell Device has two synchronization states: "in sync" and "out of sync".</p>
<p>On the Host, the internal "heartbeat" timer will always be running when Gazell is enabled, independent of the Devices' synchronization state.</p>
<p>Before any packets have been successfully received and acknowledged, the Device is out of sync. In this state, the Device switches channel determined by the <b>timeslots_per_channel_when_device_out_of_sync</b>. The Device switches channel at a slower rate than the Host (as determined by <b>timeslots_per_channel</b>) in order that the Device will eventually transmit a packet on the same channel that the Host is on.</p>
<p>When a Device successfully transmits a packet, that is when an ACK packet is received from the Host, the Device will enter "in sync" state, as it now has the information needed for continuing to "guss" the following channels the Host will be listening to.</p>
<p>For knowing when to change channel, Gazell has an internal <b>channel_index</b> counter counting the number of timeslots Gazell resides on a single channel. When this counter reaches the maximum number of timeslots, as given by <b>timeslots_per_channel</b>, the <b>channel_index</b> counter is reset and the channel is changed. This <b>channel_index</b> counter is always reset when a ACK is being received, as the Device by receiving the ACK knows the channel being used by the Host, but it can not know the <b>channel_index</b> counter state on the Host. As a result, it is only for the timeslots where the <b>channel_index</b> counter equals zero a Device can be confident that it "guesses" the correct channel that a Host is monitoring. Therfore, a new Device transmission can only be started when the <b>channel_index</b> counter on the Device is zero. Retransmission attempts, however, can be sent on all timeslots.</p>
<p>Once the Device is in sync it will keep an internal timer running in order to maintain the internal heartbeat in order to remain synchronized with the Host. The duration that the Device will stay in the in sync state is the <b>sync_lifetime</b> and is measured in timeslots. The <b>sync_lifetime</b> is reset whenever a packet is received. Once the <b>sync_lifetime</b> has expired on a Device, the internal timer is stopped and the Device will return to being out of sync.</p>
<p>Note that, whenever a Device that is "in sync" sends a packet but does not receive an ACK it will continue transmitting maximum number of transmit attempts are reached.</p>
<p>By setting the <b>sync_lifetime</b> to zero, the Device will never be in sync. The <b>sync_lifetime</b> should be chosen with regard to how often packets are required to be sent and the fact that synchronization can only be maintained for a finite time due to clock drift and radio interference. The sync lifetime is configured using <a class="el" href="group__gzll__02__api.html#ga1b34f8db6bfac6c6e232c2767a260bf3" title="Set the number of timeslots after a successful reception of a Device or Host packet that the Gazell L...">nrf_gzll_set_sync_lifetime()</a>.</p>
<p>The Device can know that sync has been achieved when the number of retransmissions gets close to zero. The <a class="el" href="structnrf__gzll__device__tx__info__t.html" title="Data structure containing information about the last packet transmission.">nrf_gzll_device_tx_info_t</a> structure is passed to the Device callback functions, and contains the number of transmit attempts required for the current packet. In addition, the <a class="el" href="structnrf__gzll__device__tx__info__t.html" title="Data structure containing information about the last packet transmission.">nrf_gzll_device_tx_info_t</a> contains the <b>num_channel_switches</b> parameter which can be used by the application to determine whether the RF channels are reliable.</p>
<h3><a class="anchor" id="addressing"></a>
Pipes and addressing</h3>
<p>Each Gazell node uses the term "pipe" as a logical address for communication with another node. Each pipe maps to one actual physical on-air address used when transmitting or receiving packets.</p>
<p>The actual on-air physical addresses are composed of a 2-4 byte long "base address" in addition to a 1 byte prefix address. The most significant byte of the base address is the first byte on the air. Note that the nRF51 radio uses an alternating sequence of 0s and 1s as the preamble of the packet. Therefore for packets to be received correctly, the most significant byte of the base address should not be an alternating sequence of 0s and 1s i.e. it should not be 0x55 or 0xAA.</p>
<p>Pipe 0 has its own unique base address, which is base address 0, while pipe 1-7 use the same base address, which is base address 1. This structure allows new nodes to pair use a shared address to initiate a new Device-Host link and then shift to a different address to continue communication. The base addresses are provided to the configuration functions as 32-bit unsigned integers with the least significant bytes being used.</p>
<p>Each of the 8 pipes have unique byte-long prefix address.</p>
<h2><a class="anchor" id="gzll_resources"></a>
Resources</h2>
<p>Gazell makes use of the following resources and requires exclusive access to them in order for Gazell to ensure correct operation:</p>
<ul>
<li>Radio (NRF_RADIO)</li>
<li>Timer (NRF_TIMER2)</li>
<li>PPI Channels 0, 1 and 2</li>
<li>Software interrupt 10 for the Gazell callback functions</li>
</ul>
<p>The radio and timer interrupt handlers run at priority level 0 (highest level), and the Gazell callback functions run at priority level 1. Applications should run at priority level 2 or higher in order to ensure correct operation.</p>
<h2><a class="anchor" id="gzll_config"></a>
Configuration</h2>
<p>Gazell can be customized at runtime for a range of different applications. See the <a class="el" href="group__gzll__02__api.html">Application Programming Interface (API)</a> for a list of configuration functions as well as the default and constant parameters. Note that editing the header file containing the default and constant parameters <b>DOES</b> <b>NOT</b> change their value when compiling a new project. These values are provided as a useful reference when making application with the precompiled library.</p>
<h2><a class="anchor" id="gzll_emulation"></a>
Emulating Legacy Gazell</h2>
<p>The Gazell Link Layer protocol for the nRF51 series is compatible with the most useful modes of the Gazell Link Layer for the nRF24Lxx devices.</p>
<h3><a class="anchor" id="gzll_emulation_dev_mode_2"></a>
Emulating legacy nRF24Lxx Gazell Device mode 2 and nRF24Lxx Host mode 0.</h3>
<p>The legacy "Device mode 2" can be emulated as follows:</p>
<ul>
<li>The channel selection policy is equivalent to <a class="el" href="group__gzll__02__api.html#ggad45683bddfd8a170f89280b722f7744ca7ac745d687a1dc56962bed8a98ba719f">NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL</a></li>
<li>When Gazell is "out of sync" a large number of attempts may occur on each channel before the channel is switched.</li>
<li>When Gazell is "in sync", a low number of transmission attempts, typically 2, are allowed on each channel before the channel is switched.</li>
</ul>
<p>The legacy "Host mode 0" has the following behavior:</p>
<ul>
<li>Host is always on while it is enabled.</li>
<li>When enabled, the Host will continuously cycle through the channel table.</li>
</ul>
<p>In addition, the relation between the Device and Host timing parameters should be as follows:</p>
<ul>
<li>The Host listens to each channel in a <b>GZLL_RX_PERIOD</b> number of microseconds, where <b>GZLL_RX_PERIOD</b> is the heartbeat interval in the nRF24Lxx devices.</li>
<li>This Host <b>GZLL_RX_PERIOD</b> must be greater than the time required committing 2 full transmission attempts on the Device (including ACK wait time).</li>
</ul>
<p>This behavior can be obtained the using the code snippet below. Here, we assume we have a channel table my_channel_table[] containing 3 channels.</p>
<p>This can be achieved using the following code snippet on the Device: </p>
<div class="fragment"><pre class="fragment"><span class="comment">/* On Host and Device */</span>
timeslots_per_channel = 2;
channel_table_size = 3;
<a class="code" href="group__gzll__02__api.html#ga3347094a64c07793c773c4fdf4bc4bff" title="Set the timeslot period.">nrf_gzll_set_timeslot_period</a>(GZLL_RX_PERIOD / 2);
<a class="code" href="group__gzll__02__api.html#ga1aa10efb06cf0cd2a5b197a4cd65deaa" title="Set the table of Radio Frequency (RF) channels.">nrf_gzll_set_channel_table</a>(my_channel_table, channel_table_size);
<a class="code" href="group__gzll__02__api.html#gaf636a5a1aa2d4a791849de510b69a604" title="Set the number of timeslots that Gazell shall reside on a single channel before switching to another ...">nrf_gzll_set_timeslots_per_channel</a>(timeslots_per_channel);
<span class="comment">/* On the Device */</span>
<a class="code" href="group__gzll__02__api.html#ga8a1bef2e6f32bd8dc55e9abde3007aed" title="Set the number of timeslots that a Gazell shall reside on a single channel before switching to anothe...">nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync</a>(channel_table_size*timeslots_per_channel);
<a class="code" href="group__gzll__02__api.html#ga692ed4d88a064fdf9a4e69f939582911" title="Set the Device channel selection policy.">nrf_gzll_set_device_channel_selection_policy</a>(<a class="code" href="group__gzll__02__api.html#ggad45683bddfd8a170f89280b722f7744ca7ac745d687a1dc56962bed8a98ba719f" title="Start on previous successful channel.">NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL</a>)
</pre></div><div class="image">
<img src="gzll_fig9_gzll_config_example.png" alt="gzll_fig9_gzll_config_example.png"/>
<div class="caption">
Emulating legacy Gazell</div></div>
</div>
</div>
  <div id="nav-path" class="navpath">
    <ul>

    <li class="footer">
      Copyright &copy 2006-2011 <a href="http://www.nordicsemi.no" style="text-decoration:none">Nordic Semiconductor</a>.
      All Rights Reserved.
      <a href="disclaimer.html">Disclaimer</a>
    </li>
   </ul>
 </div>


</body>
</html>
